Item Property (Fields Collection)
The Item
property returns a single Field
object from the collection. Read-only.
Syntax
objFieldsColl.Item(index)
objFieldsColl.Item(proptag)
objFieldsColl.Item(name [, propsetID])
objFieldsColl
Required.
Specifies the Fields collection object.
index
Short integer
(less than or equal to 65535; &Hffff). Specifies the index within the
collection.
proptag
Long integer
(greater than or equal to 65536). Specifies the property tag value for the MAPI
property to be retrieved.
name
String.
Specifies the name of the user-defined property.
propsetID
Optional.
String. Contains the unique identifier for the property set, represented as a
string of hexadecimal characters. When propsetID is not supplied, the
property set used for the access is the default property set value set by this
collection s SetNamespace method, or the initial default property set
value, PS_PUBLIC_STRINGS.
Data Type
Object
Remarks
The Item
property works like an accessor property for small collections. In the Fields
collection object it allows access to the predefined MAPI properties and to
your own custom user-defined properties.
The long
value greater than 65,535 represents a property tag. A property tag is a
32-bit unsigned integer that contains the property identifier in its high-order
16 bits and the property type (its underlying data type) in the low-order 16
bits. All MAPI properties are accessible except those of types PT_OBJECT and
PT_CLSID.
Several
macros for C/C++ programmers are available in the MAPI SDK to help manipulate
the property tag data structure. The macros PROP_TYPE and PROP_ID extract the
property type and property identifer from the property tag. The macro PROP_TAG
builds the property tag from the provided type and identifier components.
For example,
you can use the following function to access a custom user-defined property
using its property name:
' from the function Fields_ItemByName()
' error
handling here...
If
objFieldsColl Is Nothing Then
MsgBox
"must first select Fields collection"
Exit
Function
End If
Set
objOneField = objFieldsColl.Item("Keyword")
If
objOneField Is Nothing Then
MsgBox
"could not select Field object"
Exit
Function
End If
If "" = objOneField.Name Then
MsgBox
"Field has no name; ID = " & objOneField.Id
Else
MsgBox
"Field name = " & objOneField.Name
End If
You can also
use the Item property to access MAPI properties. Note that the built-in
MAPI properties are unnamed properties that can only be accessed using the
numeric value. They cannot be accessed using a string that represents the name.
The following example accesses the MAPI property PR_MESSAGE_CLASS:
' from the function Fields_Selector()
' ...
error handling here
' you can
provide a dialog to allow entry for MAPI proptags
' or
select property names from a list; for now, hard-coded
lValue =
&h1a001e ' &H1a = PR_MESSAGE_CLASS;
' &H001e = 30 = PT_STRING8
'
high-order 16 bits is property id; low-order is property type
Set
objOneField = objFieldsColl.Item(lValue)
If
objOneField Is Nothing Then
MsgBox
"Could not get the Field using the value " & lValue
Exit
Function
Else
strMsg
= "Used " & lValue & " to access the MAPI property
"
strMsg
= strMsg & "PR_MESSAGE_CLASS: type = " & objOneField.Type
strMsg
= strMsg & "; value = " & objOneField.Value
MsgBox
strMsg
End If
The OLE
Messaging Library also supports multivalued MAPI properties.
You can also
choose to access properties from other property sets, including your own, by
either setting the propsetID parameter or by calling the SetNamespace method to set that
property set s unique identifier.
The Item
property is the default property of a Fields collection, meaning that Fields(index)
is syntactically equivalent to Fields.Item(index) in Visual Basic code.
See Also
Customizing
a Folder or Message, Viewing MAPI
Properties